                Messaging Gateway WebSphere MQ SSL sample

This sample sets up a "round-trip" propagation to illustrate both
outbound (AQ->MQ) and inbound (MQ->AQ) propagation. SSL for the WebSphere MQ
connections made by the Messaging Gateway agent. An outbound propagation
job moves messages from the AQ queue MGWUSER.MGW_BASIC_SRC to a user supplied
WebSphere MQ queue. An inbound propagation job moves messages from the
same user supplied WebSphere MQ queue to the AQ queue
MGWUSER.MGW_BASIC_DEST. The end result should be messages moved from
MGWUSER.MGW_BASIC_SRC to MGWUSER.MGW_BASIC_DEST.

Files 
----------
  create_users.sql
     Creates Oracle database users, MGWUSER, MGWAGENT, MGWADM needed for
     this sample

  create_queues.sql
     Creates AQ queues needed for this sample.

  mqssl_adm_setup.sql
     Configures Messaging Gateway objects for propagating messages.
     This file must be altered by the user before it can be run.

  setup.sql
     Allows setup of this sample to be accomplished in one step. It calls
     create_users.sql, create_queues.sql, mqssl_adm_setup.sql

  mqssl_adm_cleanup.sql
     Removes the Messaging Gateway configuration for this sample.

  drop_queues.sql
     Removes the AQ queues used for this sample.

  drop_users.sql
     Drops the Oracle database users used for this sample.

  enq_basic.sql
     Enqueues a fixed message into the AQ queue used as the source for
     message propagation.

  deq_basic.sql
     Dequeues a message from the AQ queue used as the destination for
     message propagation. The message is discarded.

Preparing to Use SSL
--------------------------------------------------------------

There are a few things that must be done before running this sample.

1. Configure a WebSphere MQ server channel to use SSL.

2. Place a JSSE truststore file and a keystore file in a location 
   accessible to the host on which the Messaging Gateway agent will
   run, i.e., the host running the Oracle database.

   A truststore should always be needed since it contains the public
   certificate of the queue manager being used. A keystore should only
   be needed if SSL client authentication is used.

Refer to WebSphere documentation on configuring the channel for SSL
and tools that can be used to create the truststore and keystore if 
they do not already exist.

Configuring and running sample -- All files are SQL scripts
--------------------------------------------------------------
  1. Edit the script mqssl_adm_setup.sql (or a copy).
     There will be a block that looks as follows:
        --
        -- WARNING!!!! The values below must be set before this script is run.
        --
        begin
          :gv_database         := '';
          :gv_mq_queue_manager := ;
          :gv_mq_queue_name    := ;
          :gv_mq_channel       := ;
          :gv_mq_host          := ;
          :gv_mq_port          := ;
          :gv_mq_username      := 'mqm';
          :gv_mq_password      := 'mqm';
          :gv_mq_inbound_log_queue  := ;
          :gv_mq_outbound_log_queue := ;

          -- SSL CipherSuite used by the MQ channel;
          -- e.g., 'SSL_RSA_WITH_RC4_128_MD5'
          :gv_mq_ssl_ciphersuite := ;

          -- values for agent's Java JSSE truststore and keystore properties
          :gv_jsse_truststore          := NULL;
          :gv_jsse_truststore_password := NULL;
          :gv_jsse_keystore            := NULL;
          :gv_jsse_keystore_password   := NULL;
        end;

     Edit this block to include the appropriate values for these properties
     used for configuring a Messaging Gateway connection to WebSphere MQ. 
     These values must refer to valid WebSphere MQ entities.

  2. As user, SYS as SYSDBA, run the script, setup.sql, to create the users
     MGWUSER, MGWAGENT, and MGWADM, create the AQ queues used by this sample,
     and configure Messaging Gateway objects for propagating messages.

  3. As user, MGWADM (password MGWADM), start the Messaging Gateway agent

     e.g.  exec dbms_mgwadm.startup;

     Check the MGW_GATEWAY view and the log file (in ${ORACLE_HOME}/mgw/log) 
     to determine the status of the Messaging Gateway agent.

     e.g.  select agent_name, agent_status from MGW_GATEWAY;

  4. As user MGWUSER (password MGWUSER), enqueue a (fixed) message to the
     propagation source queue by running the script, enq_basic.sql.

  5. As a user MGWADM, check that the message has been propagated

     e.g.  select job_name, propagated_msgs, failures from MGW_JOBS;

     This will show the number of messages that have been propagated for
     each propagation job since the Messaging Gateway agent was started.

  6. Dequeue the message from the AQ queue by running the script deq_basic.sql.
     The script will return an error if no message is present. If a message
     is present it will be discarded.

Cleaning up the sample:
--------------------------------------------------------------
  1. As user MGWADM, before shutting down the Messaging Gateway agent, run
     the script, mqssl_adm_cleanup.sql, to clean up the MGW configuration.

  2. As user MGWADM, shut down the Messaging Gateway agent.

     e.g. exec dbms_mgwadm.shutdown

  3. When the Messaging Gateway agent is shut down, if desired, run the
     script, drop_queues.sql, to remove all AQ queues created for this sample.

  4. Connect as SYS as SYSDBA and run drop_users.sql to remove Oracle 
     schemas created for this sample.
